//
// Created by 张闳 on 2021/12/3.
//

#ifndef LIBMCOMMON_LIST_H
#define LIBMCOMMON_LIST_H

typedef void * mlist_t;

/*********************************************************************
 * 函数功能: 以默认方式创建一个list
 * 入口参数: 无
 * 出口参数: 无
 * 返回值  : 成功，创建的xiplist,强制转换成了void *类型,需要外部定义void*指针
            失败，返回NULL
 * 调用说明: 以默认的方式创建的list，默认值为XipListInit的默认值
            也就说XipListInit的所有参数都传递为0
            大部分情况都可以使用该函数进行一个新的hashmap的创建，如果想进行
            特殊功能，比如不分配内存，则可以调用
            list_init(该函数也对外暴露)
 *********************************************************************/
void * list_new();

/*********************************************************************
 * 函数功能: 创建一个list，有参数供特殊情况使用
 * 入口参数:  int malloc_flag 是否分配内存给value:
                1不分配,0和其他分配，具体参见XipListPut的说明
 * 出口参数: 无
 * 返回值  : 成功，创建的的st指针,强制转换成了void *类型,方便调用
            失败，返回NULL
 * 调用说明: 按照传入的信息进行定制的初始hashmap创建,
 *          如果你没有特殊的要求或特殊的场景，建议更多的使用XipHashmapNew
 *********************************************************************/
void * list_init(int malloc_flag);

/*********************************************************************
 * 函数功能: 将element存入list中
 * 入口参数: void * list
 *          void * element  任何类型，可以是整形，数组或者结构体
 *          unsigned int size 在malloc_flag不为1的情况下，
                用于帮助hasmap创建内存保存value
 * 出口参数: 无
 * 返回值  : 成功，返回保存value的地址
            失败，返回NULL
 * 调用说明: 该函数的实现与XipListInit的参数malloc_flag有关(默认为0)
            设置为1的情况: 则该List不保存实际value，只保留指向value的指针，
                         这意味着你需要在自己为所有的value,此时size参数无效
            设置为0或其他的情况:则该List在创建节点的时候，额外
                         分配内存用于对value数据的保存，调用方在使用Put之后，
                         不需要在保留原value的数据和空间
 *********************************************************************/
void * list_add(void * list, void * element, unsigned int size);

/*********************************************************************
 * 函数功能: 根据序号找到对应的value的地址
 * 入口参数: void * list
 *          int idx 序号
 * 出口参数: 无
 * 返回值  : 成功，返回保存value的地址
            未找到，返回NULL
            失败，返回NULL
 * 调用说明: 该函数的实现与XipHashmapInit的参数malloc_flag有关(默认为0)
 *********************************************************************/
void * list_get(void * list, int idx);

/*********************************************************************
 * 函数功能: 销毁和释放list，以及它所占用的空间
 * 入口参数: list指针
 * 出口参数: 无
 * 返回值  : 永远返回0
 * 调用说明: 销毁list结构和占用的空间，该函数可以多次调用.
 * 特别注意: 调用该函数之后，需要将list的值置为NULL，防止野指针，
 *          原因同free,fclose等相同。
 *********************************************************************/
int list_free(void * list);

/*********************************************************************
 * 调用功能: 打印list中所有元素
 * 入口参数: list的指针,
            ref_func(void * value) 回调函数指针
            如果不需要特殊打印，则传值为NULL
 * 出口参数: 无
 * 返回值  : 整型,不会失败，一定会返回0，所以不用判断
 * 调用说明: 值的显示目前只能显示出字符串类型，其他类型无法显示
 *********************************************************************/
/*
int list_print( void * list, ref_func);
*/
int list_print(void * list, void(*ref_func)(void *));

/*********************************************************************
 * 调用功能: 获取list当前长度
 * 入口参数: list的指针
 * 出口参数: 无
 * 返回值  : 返回长度,失败返回0
 * 调用说明:
 *********************************************************************/
int list_size(void * list);

/*********************************************************************
 * 调用功能: 获取list当前临界值
 * 入口参数: list的指针
 * 出口参数: 无
 * 返回值  : 返回临界值,失败返回0
 * 调用说明:
 *********************************************************************/
int list_threshold(void * list);

/*********************************************************************
 * 函数功能: 获取当前list所占的各种内存的大小
 * 入口参数: void * list
 * 出口参数:
 *         listsize: hashmap结构的大小,可以为NULL
 *         tablesize: 桶的大小 ,可以为NULL
 *         elesize: 节点总大小, 可以为NULL
 *         valuesize: value的总大小, 可以为NULL
 *
 * 返回值  : int total_size,占用内存总大小
 * 调用说明:
 **********************************************************************/
int list_info(void * list, int * listsize, int * tablesize, int * elesize, int * valuesize);



#endif //LIBMCOMMON_LIST_H
